Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 001a / com_and4.zip / CACMP.DOC < prev next >

Wrap

Text File | 1990-10-08 | 20KB | 880 lines

COM-AND Script Utility --------------------------------------- COM-AND Script Utility Script utility for the COM-AND language --------------------------------------- CACMP and COM-AND are distributed freely and may be copied by anyone for any number of machines, for purposes of evaluation. The author offers COM-AND and its accessory programs together as "shareware". If you USE the program a registration of $35.00 is required. The author may be reached: CABER Software R. (Scott) McGinnis P.O. Box 3607 Mdse Mart Chicago, IL 60654-0607 PLINK, GEnie id: TARTAN CIS id: 73147,2665 Version 1.0 : 901008 COM-AND Script Utility Table of Contents ----------------- I. Introduction .............................................. page 1 II. Running CACMP ............................................. page 2 III. CACMP functions ............................................ page 4 A. Syntax check ............................................ page 4 B. Semantic check .......................................... page 5 C. Partial strip ........................................... page 9 D. Full strip .............................................. page 10 E. Preprocessing ........................................... page 11 IV. CACMP and COM-AND .......................................... page 12 V. Program Requirements ....................................... page 13 VI. Program and Author Information ............................ page 14 Version 1.0 : 901008 COM-AND Script Utility Page 1 I. Introduction A. What is COM-AND? COM-AND for the IBM PC and compatibles is a communications pro- gram that may be used by itself, or with several integrated accessory programs (which themselves may be used independently of COM-AND). COM-AND provides standard comm program functions: a dialing directory, macros, disc logging, binary and ASCII file transfers, scripted execution and so on. B. COM-AND scripts A script automates certain manual tasks, and allows COM-AND to run unattended (if the script has been tested (!!!)). A script is a program written to control COM-AND execution. Scripts distributed with COM-AND include: LEARN mode (a script that writes a script), a FILEMGR (perform DOS functions and find files for transmission), a BBS, a HOST mode, and many more. Script commands are read by COM-AND from an ASCII file (word pro- cessor files are not usually ASCII files (!)). Programmer's text editors and EDLIN (provided with DOS) are be used to create and modify a script file. C. The CACMP program CACMP is a diagnostic and preprocessor for COM-AND scripts. CACMP may be used simply to perform syntax and semantic review of a COM-AND script, and it may be used to preprocess scripts for COM- AND. This document discusses the use of CACMP.EXE. COM-AND scripts and the script language are discussed in the CASCRIPT.DOC doc- ument distributed with COM-AND. Version 1.0 : 901008 COM-AND Script Utility Page 2 II. Running CACMP Generally, CACMP is invoked at the DOS prompt with the command: ----------------------------------------------------------------- "d>" CACMP <options> [<infilename> [<outfilename>]] Where "d>" is the DOS prompt, and <options> are [<switch> [<switch> ...]] ----------------------------------------------------------------- CACMP could be invoked with a command such as: "d>" CACMP to simply start CACMP. In this case, CACMP will prompt for an input file and will not write a stripped/preprocessed file. The command: "d>" CACMP /s will cause CACMP to prompt for both an input AND an output file name (the input file MUST NOT be the same as the output file). Output will be the input stripped of comments (see below). CACMP by default deletes an output file (if there is one) when a syntax error is found. This action may be inhibited with the switch "/k". In the case: "d>" CACMP /s/k the output file will be retained (and lines marked as 'syntax errors' will be retained (partially stripped, regardless of preprocessing). The input file name (and output file name) may be specified in the run command. For example: "d>" CACMP /s bbs.src will read the file BBS.SRC and prompt for an output file name. Input file names default to the extension ".CMD" if the name given is not found. The output file, if it exists, is deleted and recreated when CACMP begins. For this reason, CACMP must not be run with the same file as INPUT and output. Version 1.0 : 901008 COM-AND Script Utility Page 3 II. Running CACMP (continued) The following switches are defined for CACMP at run-time: /1 Partial strip output (see below) /s Full strip output (see below) /k Keep output if syntax error is detected /p Preprocess script (for speed) The default settings for CACMP are: no output, and delete output if a syntax error is detected. All error and diagnostic output by CACMP is directed to the standard output device. Therefore, the command: "d>" CACMP >temp script.cmd records all the diagnostic information in the file TEMP on the cur- rent subdirectory, for later review. When CACMP terminates it displays the following summary: Total input lines: Total input statements: Total input comments: Total input labels: Total syntax errors: Total semantic warnings: If output was created, CACMP also reports: Input file size: Output file size: CACMP terminates with a DOS error level of 0 if no syntax errors and no semantic errors were detected. CACMP terminates with a DOS error level of 1 if either syntax or semantic errors were reported. [Batch checks of a group of scripts may be stopped on an error using the error level returned to DOS.] Version 1.0 : 901008 COM-AND Script Utility Page 4 III. CACMP functions A. Syntax check CACMP's first function is to syntactically verify each line of the input file. Syntax errors are noted as follows: Line 3: Syntax error S0 = N0+5(N1+ N2) ^ General parse failure (syntax) The first line records the line number and the error. The second line echoes the input line. The third line points to the highest point the parser reached parsing the line (probably close to the point at which the error occurs). The fourth line adds any addi- tional information returned by the parser. Developer's note: In the fourth line, ANY return except the one above should be reported to the author. The fourth line properly may be considered diagnostic to CACMP. For example, 'Stack overflow' at this point indicates that the parser recursed beyond its stack - a CACMP problem and not an input problem. All error and diagnostic information listed by CACMP is directed to the standard output device. Therefore, the command: "d>" CACMP >temp script.cmd records all CACMP diagnostic information in the file TEMP on the current subdirectory, for later review. Syntax errors are counted, and the number reported at CACMP ter- mination. If CACMP was run to strip/preprocess a file and syntax errors were detected, the output file is deleted (unless /k in the run command was specified). Version 1.0 : 901008 COM-AND Script Utility Page 5 III. CACMP functions (continued) B. Semantic check Beyond syntactic verification of each line, CACMP follows the input file to verify the structure of the script. Semantic verification in CACMP consists of: 1. Overlapped domains The IF, SWITCH, WHILE, FOR and DO statements imply a 'domain' of execution. The domain of the IF statement extends until an ENDIF statement (except in compound IF statements, where a single statement to be executed when the condition is true is carried on the same line). The domain of a SWITCH statement extends until an ENDSWITCH. Similarly the WHILE, FOR and DO statements domains extend until their respective terminators. Domains may NOT overlap. For example, the following construction is an overlapped domain: WHILE N0 LT 5 IF N0 EQ 3 ENDWHILE GOTO somewhere ENDIF ENDWHILE [In the above case, the ENDWHILE within the IF domain is superfluous (the WHILE loop domain would terminate on the GOTO).] CACMP diagnoses this code as: Line 3: WARNING: Overlapped domain ENDWHILE ^ ....... Current domain is IF starting: 2 The ENDWHILE on line 3 overlaps the IF domain that began in line 2. Version 1.0 : 901008 COM-AND Script Utility Page 6 III. CACMP functions (continued) B. Semantic check (continued) 2. Incomplete domain On completion of processing, domains left open (i.e. with- out closure) are reported as 'incomplete domains' by CACMP. For example: WARNING: Incomplete WHILE domain starting: 1 In this case, a WHILE loop was not properly closed with an ENDWHILE. The WHILE statement is to be found in line 1. 3. Unreachable code The GOTO, RETURN, FRETURN, ACCESSORY, EXECUTE, EXIT, BYE, TERMINAL, CONNECT, and QUIT statements are unconditional transfers of control. They do not return. When one of these statements is found OUTSIDE of the domain of an IF, WHILE, SWITCH, FOR, or DO statement, CACMP expects to find a label as the next executable statement. If not, CACMP issues the following semantic warning: Line 2: WARNING: Cannot reach this statement N0 = N0+1 ^ 4. Duplicate labels CACMP keeps track of label statements. When a label dupli- cates one previously seen, CACMP issues the warning: Line 9: WARNING: Duplicate label label: ^ Note that the label has been truncated to 8 characters. COM- AND only uses the first 8 characters of a label - often the root of a duplicate label condition. Version 1.0 : 901008 COM-AND Script Utility Page 7 III. CACMP functions (continued) B. Semantic check (continued) 5. Undefined labels CACMP also keeps track of label used in GOTO, GOSUB, ON and WOPEN statements. On completion of processing, any label referenced by one of these statements but not found in the script is reported as 'undefined label'. For example: WARNING: Undefined label: SOMEWHER 6. Label in domain (IF/SWITCH/WHILE/FOR/DO) Above it was noted that a GOTO terminates the 'domain' of an IF, SWITCH, WHILE, FOR, and DO statement. GOTOs may NOT transfer control INTO the domain of one of these statements. When a label is encountered within a domain, CACMP reports: Line 8: WARNING: Label in WHILE domain starting: 3 label: ^ It will be noted (painfully), that a single unclosed domain (for example, an IF missing its ENDIF) may result in MANY 'label in domain' warnings. The clue in this case is that all will reference a domain beginning at one line. Correct the unclosed domain, and improper 'label in domain' warnings disappear. Version 1.0 : 901008 COM-AND Script Utility Page 8 III. CACMP functions (continued) B. Semantic check (continued) 7. COM-AND stack overflow COM-AND allows IF, WHILE, SWITCH, FOR and DO statements to be nested to a depth of 20. When CACMP finds a nesting level greater than 20 it issues a warning: WARNING: DO/FOR/IF/SWITCH/WHILE stack overflow WHILE 1 EQ 1 ^ 8. COM-AND stack underflow When an ENDIF, ENDWHILE, ENDSWITCH, ENDFOR or UNTIL statement is encountered with no corresponding start-of-domain state- ment, CACMP issues the warning: WARNING: DO/FOR/IF/SWITCH/WHILE stack underflow ENDWHILE ^ Version 1.0 : 901008 COM-AND Script Utility Page 9 III. CACMP functions (continued) C. Partial strip When CACMP is run with the /1 switch, records of the input file are 'partially stripped' and written to the output file. Partial stripping is similar in function to the STRIPPER.CMD script dis- tributed with COM-AND. Partial stripping consists of: 1) Removal of comment lines 2) Removal of comments on statement lines 3) Removal of all blanks at the left of a statement 4) Reduction of multiple blanks to a single blank 5) Removal of redundant blanks (e.g. " = " -> "=") The STRIPPER.CMD script only performs function (1) above. Addi- ally, CACMP writes the output file records with only a carriage return (not carriage return/line feed), as COM-AND needs only the carriage return. A file 'partially stripped' by CACMP will be smaller than one stripped by STRIPPER. The actual reduction in size will be determined by the input file, but CACMP necessarily produces a smaller file. Please note that once stripped by CACMP, a file may not be 'read- able' by the same editor that produced its source. Some editors will tolerate the missing line feed, and some won't. The popular LIST program by Vern Buerg, for example, won't display the file (except as a hex dump). Lines marked as 'syntax errors' are written to the output file partially stripped. Version 1.0 : 901008 COM-AND Script Utility Page 10 III. CACMP functions (continued) D. Full Strip When CACMP is run with the /s switch, records of the input file are 'fully stripped' and written to the output file. Full stripping includes the functions listed above as 'partial stripping', and: 1) Reduction of label lines to an 8 character maximum 2) Reduction of labels in GOTO, GOSUB, ON and WOPEN statements to an 8 character maximum 3) Reduction of initial keywords in statements to a four character maximum. Again, CACMP writes the output file records with only a carriage return (not carriage return/line feed) as COM-AND needs only the carriage return. A file 'fully stripped' by CACMP will be considerably smaller than one stripped by STRIPPER. The actual reduction in size will be determined by the input file. [Your mileage may vary, contents are shipped by weight, not volume...] Lines marked 'syntax errors' are written to the output file, but only partially stripped. [Tricky ones in the audience might propose that labels be con- verted to numeric equivalents. After all, "1:" is a legitimate label. However, the COM-AND language supports indirect GOTOs. For example, "GOTO S0" will branch to the label in S0 (given that S0 contains a valid label name). Therefore, such a reduction, although generally possible, is not supported.] Version 1.0 : 901008 COM-AND Script Utility Page 11 III. CACMP functions (continued) E. Preprocessing When CACMP is run with the /P switch, records of the input file will be 'preprocessed' and written to the output file. Prepro- cessing performs the full strip as described above, and: . adds a two byte keyword to each executable line to speed COM-AND's execution of the statement Preprocessed scripts are accepted by COM-AND as of its version 2.7. The two-byte code added to each executable line speeds the interpretor's execution of the statement. [Author's note: the two byte keyword may easily be recognized - the first byte is always negative (larger than 127).] A file 'preprocessed' by CACMP will be larger than one stripped by CACMP. It will execute approximately 30% faster than the same script stripped by CACMP. [Please note, preprocessing does not have any effect on writes to screen or disc. It simply speeds the interpretation of script statements.] Lines marked 'syntax errors' are written to the output file, but only partially stripped. They are not preprocessed. Version 1.0 : 901008 COM-AND Script Utility Page 12 IV. CACMP and COM-AND CACMP implements a parser based upon a meta-language specification of the COM-AND language. COM-AND does not - its interpretor parses ad hoc (or if you wish, on-the-fly). The advantages of ad hoc interpre- tation are: 1) execution speed, and 2) simplicity of extension The disadvantage of ad hoc interpretation is that a syntax/semantic utility such as CACMP is not possible (not based on the interpretor's code, at least). The important point is that CACMP may kick out perfectly valid state- ments because its meta-language statement of the language does not accommodate a particular construction. COM-AND executes the state- ment happily, but CACMP rejects it. The language syntax implemented is taken from version 2.6 COM-AND documentation... however, COM-AND proper (not its documentation) will be the final arbiter of syntax (and documentation adjusted accordingly <smile>). If you use this, please save doubtful reports and submit them to the developer. Such reports will be used to further refine CACMP. For the curious, the meta-language implemented here is similar in form to the LANGPACK language developed at Bell Labs. LANGPACK per se was not implemented - the modified Backus-Naur form for the meta- language was implemented in a lexical compiler created for CACMP. The parser implemented uses the lexical compiler's output to control text parsing. Version 1.0 : 901008 COM-AND Script Utility Page 13 V. Program requirements CACMP is written for an IBM PC or DOS compatible machine. CACMP uses DOS and BIOS for all I/O... no fancy games with screen buffers are played. COM-AND disk I/O is done through the 'Handle' oriented I/O routines added to DOS 2.0. Therefore DOS 2.0 is a minimum requirement. CACMP (Version 1.0 ) requires 107K for itself. You need 256K to take advantage of it. Version 1.0 : 901008 COM-AND Script Utility Page 14 VI. Author information CACMP was written using Microsoft Macro-Assembler. The author likes assembler. Assembly language is an entirely appropriate vehicle for some of the program, and a not-inappropriate vehicle for the rest of it. Everything, in moderation... The author of this program is R. Scott McGinnis of Chicago, IL. PLINK and GEnie ID: TARTAN. CIS ID: 73147,2665. Comment and suggestions (and criticism in moderation) are welcomed: CABER Software R. (Scott) McGinnis P.O. Box 3607 Mdse Mart Chicago, IL 60654-0607 I thank my wife, Elizabeth, who put up with my obsessing while I developed the parser on which CACMP is based. The meta-language specification of a language the size of COM-AND's is an obsessive task - writing a compiler to compile the meta-language and a parser to execute the compiler's output... the mind is a terrible thing to lose. Elizabeth refreshes this one every day. This program may be distributed freely (but it isn't a whole lot of use without COM-AND). Any problems that are reported to the author will get attention. COM-AND is shareware. If COM-AND is USED after a reasonable period of evaluation, a registration of $35.00 is required. CACMP is included in the registration of COM-AND. Version 1.0 : 901008